Python FastAPI Virheiden Käsittely: Vankkojen Mukautettujen Poikkeuskäsittelijöiden Rakentaminen

Virheiden käsittely on olennainen osa vankkojen ja luotettavien API:en rakentamista. Pythonin FastAPI:ssä voit hyödyntää mukautettuja poikkeuskäsittelijöitä virheiden hallitsemiseksi sulavasti ja tarjotaksesi informatiivisia vastauksia asiakkaille. Tämä blogikirjoitus opastaa sinut mukautettujen poikkeuskäsittelijöiden luomisessa FastAPI:ssä, mikä mahdollistaa joustavampien ja käyttäjäystävällisempien sovellusten rakentamisen.

Miksi Mukautetut Poikkeuskäsittelijät?

FastAPI tarjoaa sisäänrakennetun tuen poikkeusten käsittelyyn. Kuitenkin, pelkästään oletusvirhevasteisiin luottaminen voi jättää asiakkaille epämääräistä tai hyödytöntä tietoa. Mukautetut poikkeuskäsittelijät tarjoavat useita etuja:

• Parannettu Käyttökokemus: Tarjoa selkeitä ja informatiivisia virheilmoituksia, jotka on räätälöity tiettyihin virhetilanteisiin.
• Keskitetty Virheiden Hallinta: Yhdistä virheiden käsittelylogiikka yhteen paikkaan, mikä tekee koodistasi ylläpidettävämpää.
• Yhtenäiset Virhevasteet: Varmista, että virhevasteet noudattavat yhtenäistä muotoa, mikä parantaa API:n käytettävyyttä.
• Parannettu Turvallisuus: Estä arkaluonteisten tietojen paljastuminen virheilmoituksissa.
• Mukautettu Kirjaaminen: Kirjaa yksityiskohtaista virhetietoa virheenkorjaus- ja valvontatarkoituksiin.

FastAPI:n Poikkeusten Käsittelyn Ymmärtäminen

FastAPI käyttää yhdistelmää Pythonin sisäänrakennettuja poikkeusten käsittelymekanismeja ja omaa riippuvuuksien injektointijärjestelmäänsä virheiden hallintaan. Kun poikkeus nostetaan reitissä tai riippuvuudessa, FastAPI etsii sopivan poikkeuskäsittelijän sen käsittelemiseksi.

Poikkeuskäsittelijät ovat funktioita, jotka on koristeltu @app.exception_handler() -koristeella, ja jotka ottavat kaksi argumenttia: poikkeustyypin ja pyyntöobjektin. Käsittelijä on vastuussa sopivan HTTP-vasteen palauttamisesta.

Mukautettujen Poikkeusten Luominen

Ennen mukautettujen poikkeuskäsittelijöiden määrittämistä on usein hyödyllistä luoda mukautettuja poikkeusluokkia, jotka edustavat sovelluksesi tiettyjä virhetiloja. Tämä parantaa koodin luettavuutta ja helpottaa erityyppisten virheiden käsittelyä.

Oletetaan esimerkiksi, että olet rakentamassa verkkokaupan API:a ja sinun on käsiteltävä tapauksia, joissa tuote on loppu. Voit määrittää mukautetun poikkeusluokan nimeltä OutOfStockError:

            
class OutOfStockError(Exception):
    def __init__(self, product_id: int):
        self.product_id = product_id
        self.message = f"Tuote ID:llä {product_id} on loppu."

            

              
                Copy
              
            
          

Tämä mukautettu poikkeusluokka perii pohja-Exception-luokan ja sisältää product_id-attribuutin ja mukautetun virheilmoituksen.

Mukautettujen Poikkeuskäsittelijöiden Toteuttaminen

Luodaan nyt mukautettu poikkeuskäsittelijä OutOfStockError-virheelle. Tämä käsittelijä sieppaa poikkeuksen ja palauttaa HTTP 400 (Bad Request) -vasteen JSON-rungon kanssa, joka sisältää virheilmoituksen.

            
from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse

app = FastAPI()

class OutOfStockError(Exception):
    def __init__(self, product_id: int):
        self.product_id = product_id
        self.message = f"Tuote ID:llä {product_id} on loppu."

@app.exception_handler(OutOfStockError)
async def out_of_stock_exception_handler(request: Request, exc: OutOfStockError):
    return JSONResponse(
        status_code=400,
        content={"message": exc.message},
    )

@app.get("/products/{product_id}")
async def get_product(product_id: int):
    # Simuloi tuotevaraston tarkistamista
    if product_id == 123:
        raise OutOfStockError(product_id=product_id)
    return {"product_id": product_id, "name": "Esimerkkituote", "price": 29.99}

            

              
                Copy
              
            
          

Tässä esimerkissä @app.exception_handler(OutOfStockError) -koriste rekisteröi out_of_stock_exception_handler -funktion käsittelemään OutOfStockError-poikkeuksia. Kun OutOfStockError nostetaan get_product-reitissä, poikkeuskäsittelijä kutsutaan. Käsittelijä palauttaa sitten JSONResponse-vastauksen, jonka tilakoodi on 400 ja JSON-runko sisältää virheilmoituksen.

Useiden Poikkeustyyppien Käsittely

Voit määrittää useita poikkeuskäsittelijöitä käsittelemään erityyppisiä poikkeuksia. Haluat ehkä esimerkiksi käsitellä ValueError-poikkeuksia, joita ilmenee jäsennettäessä käyttäjän syötettä.

            
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(ValueError)
async def value_error_exception_handler(request: Request, exc: ValueError):
    return JSONResponse(
        status_code=400,
        content={"message": str(exc)},
    )

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    # Simuloi virheellistä item_id:tä
    if item_id < 0:
        raise ValueError("Tuotteen ID:n on oltava positiivinen kokonaisluku.")
    return {"item_id": item_id, "name": "Esimerkkituote"}

            

              
                Copy
              
            
          

Tässä esimerkissä value_error_exception_handler-funktio käsittelee ValueError-poikkeuksia. Se poimii virheilmoituksen poikkeusobjektista ja palauttaa sen JSON-vastauksessa.

HTTPException:n Käyttäminen

FastAPI tarjoaa sisäänrakennetun poikkeusluokan nimeltä HTTPException, jota voidaan käyttää HTTP-kohtaisten virheiden nostamiseen. Tämä voi olla hyödyllistä yleisten virhetilanteiden, kuten luvattoman pääsyn tai resurssin puuttumisen, käsittelyssä.

            
from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    # Simuloi käyttäjän puuttumista
    if user_id == 999:
        raise HTTPException(status_code=404, detail="Käyttäjää ei löytynyt")
    return {"user_id": user_id, "name": "Esimerkkikäyttäjä"}

            

              
                Copy
              
            
          

Tässä esimerkissä HTTPException nostetaan tilakoodilla 404 (Not Found) ja yksityiskohtaisella ilmoituksella. FastAPI käsittelee automaattisesti HTTPException-poikkeukset ja palauttaa JSON-vastauksen määritetyllä tilakoodilla ja yksityiskohtaisella ilmoituksella.

Globaalit Poikkeuskäsittelijät

Voit myös määrittää globaaleja poikkeuskäsittelijöitä, jotka sieppaavat kaikki käsittelemättömät poikkeukset. Tämä voi olla hyödyllistä virheiden kirjaamisessa tai yleisen virheilmoituksen palauttamisessa asiakkaalle.

            
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import logging

app = FastAPI()

logger = logging.getLogger(__name__)

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    logger.exception(f"Käsittelemätön poikkeus: {exc}")
    return JSONResponse(
        status_code=500,
        content={"message": "Sisäinen palvelinvirhe"},
    )

@app.get("/error")
async def trigger_error():
    raise ValueError("Tämä on testivirhe.")

            

              
                Copy
              
            
          

Tässä esimerkissä global_exception_handler-funktio käsittelee kaikki poikkeukset, joita muut poikkeuskäsittelijät eivät käsittele. Se kirjaa virheen ja palauttaa 500 (Internal Server Error) -vastauksen yleisellä virheilmoituksella.

Väliohjelmiston Käyttäminen Poikkeusten Käsittelyyn

Toinen lähestymistapa poikkeusten käsittelyyn on väliohjelmiston käyttäminen. Väliohjelmistofunktiot suoritetaan ennen ja jälkeen jokaista pyyntöä, jolloin voit siepata ja käsitellä poikkeuksia korkeammalla tasolla. Tämä voi olla hyödyllistä tehtävissä, kuten pyyntöjen ja vasteiden kirjaamisessa tai mukautetun todennus- tai valtuutuslogiikan toteuttamisessa.

            
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
import logging

app = FastAPI()

logger = logging.getLogger(__name__)

@app.middleware("http")
async def exception_middleware(request: Request, call_next):
    try:
        response = await call_next(request)
    except Exception as exc:
        logger.exception(f"Käsittelemätön poikkeus: {exc}")
        return JSONResponse(
            status_code=500,
            content={"message": "Sisäinen palvelinvirhe"},
        )
    return response

@app.get("/error")
async def trigger_error():
    raise ValueError("Tämä on testivirhe.")

            

              
                Copy
              
            
          

Tässä esimerkissä exception_middleware-funktio käärii pyynnön käsittelylogiikan try...except-lohkoon. Jos pyynnön käsittelyn aikana ilmenee poikkeus, väliohjelmisto kirjaa virheen ja palauttaa 500 (Internal Server Error) -vastauksen.

Esimerkki: Kansainvälistyminen (i18n) ja Virheilmoitukset

Kun rakennat API:eja globaalille yleisölle, harkitse virheilmoitusten kansainvälistämistä. Tämä tarkoittaa virheilmoitusten tarjoamista eri kielillä käyttäjän alueasetusten perusteella. Täydellisen i18n-toteutuksen toteuttaminen on tämän artikkelin laajuuden ulkopuolella, tässä on yksinkertaistettu esimerkki, joka havainnollistaa konseptia:

            
from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import JSONResponse
from typing import Dict

app = FastAPI()

# Mock translation dictionary (replace with a real i18n library)
translations: Dict[str, Dict[str, str]] = {
    "en": {
        "product_not_found": "Product with ID {product_id} not found.",
        "invalid_input": "Invalid input: {error_message}",
    },
    "fr": {
        "product_not_found": "Produit avec l'ID {product_id} introuvable.",
        "invalid_input": "Entrée invalide : {error_message}",
    },
    "es": {
        "product_not_found": "Producto con ID {product_id} no encontrado.",
        "invalid_input": "Entrada inválida: {error_message}",
    },
    "de": {
        "product_not_found": "Produkt mit ID {product_id} nicht gefunden.",
        "invalid_input": "Ungültige Eingabe: {error_message}",
    }
}

def get_translation(locale: str, key: str, **kwargs) -> str:
    """Retrieves a translation for a given locale and key.
    If the locale or key is not found, returns a default message.
    """
    if locale in translations and key in translations[locale]:
        return translations[locale][key].format(**kwargs)
    return f"Translation missing for key '{key}' in locale '{locale}'."

@app.get("/products/{product_id}")
async def get_product(request: Request, product_id: int, locale: str = "en"):
    # Simulate product lookup
    if product_id > 100:
        message = get_translation(locale, "product_not_found", product_id=product_id)
        raise HTTPException(status_code=404, detail=message)

    if product_id < 0:
         message = get_translation(locale, "invalid_input", error_message="Product ID must be positive")
         raise HTTPException(status_code=400, detail=message)

    return {"product_id": product_id, "name": "Example Product"}

            

              
                Copy
              
            
          

Keskeisiä parannuksia i18n-esimerkkiin:

• Paikallisparametrit: Reitti hyväksyy nyt locale-kyselyparametrin, jonka avulla asiakkaat voivat määrittää haluamansa kielen (oletusarvoisesti "en" englanniksi).
• Käännössanakirja: translations-sanakirja (mock) tallentaa virheilmoituksia eri paikkakunnille (englanti, ranska, espanja, saksa tässä tapauksessa). Todellisessa sovelluksessa käytät erillistä i18n-kirjastoa.
• get_translation-funktio: Tämä apufunktio hakee sopivan käännöksen locale- ja key-arvojen perusteella. Se tukee myös merkkijonojen muotoilua dynaamisten arvojen (kuten product_id) lisäämiseksi.
• Dynaamiset virheilmoitukset: HTTPException nostetaan nyt detail-ilmoituksella, joka on luotu dynaamisesti get_translation-funktion avulla.

Kun asiakas pyytää /products/101?locale=fr, hän saa virheilmoituksen ranskaksi (jos käännös on saatavilla). Kun pyydetään /products/-1?locale=es, he saavat virheilmoituksen negatiivisesta ID:stä espanjaksi (jos saatavilla). Kun pyydetään /products/200?locale=xx (paikkakunta, jolla ei ole käännöksiä), he saavat viestin `Käännös puuttuu`.

Parhaat Käytännöt Virheiden Käsittelyyn

Tässä on joitain parhaita käytäntöjä, jotka kannattaa pitää mielessä, kun toteutat virheiden käsittelyä FastAPI:ssä:

• Käytä Mukautettuja Poikkeuksia: Määritä mukautettuja poikkeusluokkia edustamaan sovelluksesi tiettyjä virhetiloja.
• Anna Informatiivisia Virheilmoituksia: Sisällytä selkeitä ja ytimekkäitä virheilmoituksia, jotka auttavat asiakkaita ymmärtämään virheen syyn.
• Käytä Sopivia HTTP-Tilakoodeja: Palauta HTTP-tilakoodeja, jotka heijastavat tarkasti virheen luonnetta. Käytä esimerkiksi 400 (Bad Request) -koodia virheelliselle syötteelle, 404 (Not Found) -koodia puuttuville resursseille ja 500 (Internal Server Error) -koodia odottamattomille virheille.
• Vältä Arkaluonteisten Tietojen Paljastamista: Ole varovainen, ettet paljasta arkaluonteisia tietoja, kuten tietokannan tunnistetietoja tai API-avaimia virheilmoituksissa.
• Kirjaa Virheet: Kirjaa yksityiskohtaista virhetietoa virheenkorjaus- ja valvontatarkoituksiin. Käytä kirjaamiskirjastoa, kuten Pythonin sisäänrakennettua logging-moduulia.
• Keskitä Virheiden Käsittelylogiikka: Yhdistä virheiden käsittelylogiikka yhteen paikkaan, kuten mukautettuihin poikkeuskäsittelijöihin tai väliohjelmistoon.
• Testaa Virheiden Käsittelysi: Kirjoita yksikkötestejä varmistaaksesi, että virheiden käsittelylogiikkasi toimii oikein.
• Harkitse Erillisen Virheiden Seurantapalvelun Käyttämistä: Tuotantoympäristöissä harkitse erillisen virheiden seurantapalvelun, kuten Sentryn tai Rollbarin, käyttämistä virheiden valvomiseksi ja analysoimiseksi. Nämä työkalut voivat tarjota arvokasta tietoa sovelluksesi kunnosta ja auttaa sinua tunnistamaan ja ratkaisemaan ongelmia nopeasti.

Johtopäätös

Muista ottaa käyttökokemus huomioon suunnitellessasi virheiden käsittelystrategiaasi. Anna selkeitä ja ytimekkäitä virheilmoituksia, jotka auttavat käyttäjiä ymmärtämään ongelman ja sen ratkaisemisen. Tehokas virheiden käsittely on kulmakivi laadukkaiden API:en rakentamisessa, jotka vastaavat monipuolisen globaalin yleisön tarpeita.